home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Vollversion / CamD / development / docs / camd.intro < prev    next >
Text File  |  2000-05-15  |  13KB  |  257 lines
  1. =========================================================================
  2.                        Commodore-Amiga Midi Driver
  3. =========================================================================
  4.  
  5. Introduction
  6. ~~~~~~~~~~~~
  7.     CAMD is an Amiga shared library which provides a general device driver
  8. for MIDI data, so that applications can share MIDI data with each other in
  9. real-time, and interface to MIDI hardware in a device-independent way.
  10.  
  11. Goals
  12. ~~~~~
  13.     The goals of CAMD are:
  14.  
  15.     1. To encourage development of music software and synchronized
  16. multimedia applications by providing a working driver to the public.
  17.  
  18.     2. To enable music and multimedia applications to operate concurrently
  19. and exchange MIDI data in real-time.
  20.  
  21.     3. To improve on existing "freeware" drivers by enhancing performance,
  22. by providing hooks for getting raw input, and by simplifying the interface
  23. as much as possible.
  24.  
  25. Operating System Requirements
  26. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  27.     The CAMD library functions identically under 2.0 or 1.3. However, many
  28. of the various utilities that come with CAMD require GadTools or other 2.0
  29. features. One of the most important of these is the "MIDI Ports"
  30. preferences editor, which is used to tell CAMD which hardware ports to
  31. use. Note that if the preferences file is missing, CAMD will always fall
  32. back on opening the Amiga's internal serial port. What this means is that
  33. applications that run under 1.3 can use CAMD, but until a preferences
  34. editor that works under 1.3 has been created the functionality will be
  35. reduced.
  36.  
  37. The MIDI System
  38. ~~~~~~~~~~~~~~~
  39.     The MIDI distribution system is based on the idea of "linkages"
  40. (called MidiLinks) between applications. Each application or hardware
  41. driver can establish linkages to other applications or hardware drivers.
  42. Multiple links can be established to a single source, so that more than
  43. one application can see the MIDI stream coming out of a hardware port or
  44. application output. Similarly, more than one application can send a MIDI
  45. stream to a single hardware port or application input. The ability to have
  46. one application send data to another allows "pipelining" of the MIDI
  47. stream, for example connecting an interactive composing program to a
  48. sequencer and running both concurrently.
  49.     Note that there is no requirement that the data sent actually be valid
  50. musical data -- it is possible for a pair of applications to set up a private
  51. linkage, and communicate anything they want, as long as it follows the
  52. syntactic rules of MIDI. However, it is suggested that such linkages be
  53. hidden from the user (using a special bit which makes a linkage private),
  54. since the eventually there will be a "patch editor" which will allow the
  55. user to manipulate linkages without the application being aware of it.
  56.  
  57.     Each MIDI application must create a MidiNode. This structure is used
  58. as a central dispatch point for incoming and outgoing messages, and holds
  59. all of the application-specific information, including:
  60.     -- location and size of input buffers.
  61.     -- the name of the application
  62.     -- the icon to be used for the application in the patch editor.
  63.     -- the address of the task to signal when messages are received, and
  64.             the signal bit to use.
  65.  
  66. MIDI Messages
  67. ~~~~~~~~~~~~~
  68.     Each MIDI message sent or received is contained in a MidiMsg
  69. structure. This 8-byte structure contains a timestamp, the actual MIDI
  70. bytes (up to 3) and a link number (so that applications which have several
  71. input links can determine which one received the message). Note that since
  72. the message is so small, the entire message is copied when MIDI data is
  73. transferred, rather than passing pointers around.
  74.  
  75. How MIDI Data is received
  76. ~~~~~~~~~~~~~~~~~~~~~~~~~
  77.     MIDI applications can be either task-based or callback based. A
  78. task-based application uses a signal to wait for incoming MIDI data. Once
  79. the signal is received, the application can call GetMidi() to actually
  80. look at what was received. All incoming messages are queued, and there is
  81. a seperate queue for system exclusive messages (which can be quite long).
  82. Each incoming MIDI event is both timestamped and marked with the linkage
  83. number (settable by the application) from the link that it came in on.
  84.     Some people have questioned whether a task can respond fast enough to
  85. incoming MIDI data to meet professional standards of timing accuracy. Our
  86. experimentation has determined that a high-priority task (say, 30 or so),
  87. can meet these reqiuirements, even when the disk drive is running.
  88.     However, if the application's handling of MIDI is very fast, it may be
  89. better to use a callback. The callback occurs in the context of the
  90. sender, so it is best to be quick so as not to slow down the sending task.
  91. (Note that the sender will always be a task, and not an interrupt, since
  92. the actual hardware drivers are serviced via a task) The callback is
  93. invoked through a standard Hook structure. Using a callback avoids the
  94. overhead of task switching, and can allow improved overall performance.
  95.  
  96. How MIDI Data is Sent
  97. ~~~~~~~~~~~~~~~~~~~~~
  98.     Sending MIDI data is very simple, mainly a matter of filling out a
  99. MidiMsg structure and calling PutMidi(). Note that if the receive buffer
  100. is full, then the function will fail, rather than waiting for the receive
  101. buffer to empty.
  102.  
  103. System Exclusive
  104. ~~~~~~~~~~~~~~~~
  105.     For those of you not familier with MIDI, system exclusive messages
  106. (called SysEx for short) are a kind of escape hatch in the MIDI spec which
  107. allows developers to define their own messages. Unlike other MIDI events
  108. which are limited to 3 bytes or less, SysEx messages can be any length. In
  109. CAMD, SysEx messages are handled by placing the header of the message (the
  110. first three bytes) in the regular receive queue as a MidiMsg, and placing
  111. the full message in a seperate buffer. The receiver can look at the first
  112. three bytes, and decide whether they want to read the rest by calling
  113. GetSysEx() or throw it away by calling SkipSysEx();
  114.     Sending SysEx is done by calling the function PutSysEx().
  115.  
  116. Filters
  117. ~~~~~~~
  118.     To reduce the load on the system, MIDI data can be filtered so that
  119. only useful data shows up in the application's input buffer. Each MidiLink
  120. has a set of filter bits, can allow incoming messages to be ignored (not
  121. placed in the receive queue). The first set of filter bits correspond to
  122. the 16 MIDI channels. (For those of you unfamilier with MIDI, the low
  123. nybble of the first MIDI byte contains the channel number). If the
  124. incoming MIDI messages is on a channel which does not correspond to one of
  125. the bits set in the filter word. the message is skipped. A second filter
  126. is based on the type of the event, of which CAMD breaks up into 14
  127. categories:
  128.  
  129.     -- note on/off
  130.     -- program change
  131.     -- pitch bend
  132.     -- controller change MSB
  133.     -- controller change LSB
  134.     -- controller change boolean switch
  135.     -- controller change single byte
  136.     -- controller parameter change
  137.     -- undefined controllers
  138.     -- mode change messages
  139.     -- channel after touch
  140.     -- polyphonic after touch
  141.     -- system real-time messages (MIDI clock, MTC Quarter Frame)
  142.     -- system common messages (Start, Stop, etc)
  143.     -- system exclusive messages
  144.  
  145.     In addition, there is a special filtering system for SysEx messages
  146. which allows them to be filtered based on the first byte or the first
  147. three bytes after the SysEx header byte. If the first byte only is used,
  148. then three different filters can be specified. If the first three bytes
  149. are used, then only one filter can be specified.
  150.  
  151. Establishing Links
  152. ~~~~~~~~~~~~~~~~~~
  153.     One of the nice thing about MidiLinks is that they can be established
  154. even if the other application or hardware driver hasn't been loaded yet.
  155. This is because a MidiLink does not connect directly to the other
  156. application, but rather it connects to a "meeting place" or "rendevous
  157. point" for MidiLinks called a Cluster. Each cluster is referred to by
  158. name. For example, if I establish an output link to the cluster "foo", and
  159. someone else establishes an input link to that same cluster, then any data
  160. that my application sends to that link will be received by that other
  161. application. If a third application creates an input link to "foo", then
  162. it will also receive the data, whereas if another application creates an
  163. output link to "foo" then it's MIDI data will be merged with mine, and
  164. distributed to all the input links.
  165.     So the rules of clusters are as follows:
  166.  
  167.     -- The first attempt to link to a cluster creates the cluster, and
  168.         the last link to leave deletes it.
  169.  
  170.     -- Each sender link to a cluster is merged with all the other senders.
  171.  
  172.     -- Each receiver link to a cluster gets a copy of what all the other
  173.         receivers get.
  174.  
  175.     In addition, there are some other properties of clusters:
  176.  
  177.     Participants: The library function MidiLinkConnected() can be used to
  178. check a cluster to see if there are any linkages of the opposite type. For
  179. example, a sender could check to see if anybody is listening or if they
  180. are just talking to vacuum. Similarly, a receiver could check to see if
  181. there are any senders. In addition, you can request to be notified (via
  182. signal) whenever the participants in a cluster change. This feature is
  183. primarily used by the hardware interface in the library itself -- it
  184. allows a driver to be shut down (and freeing the hardware resources) when
  185. there are no applications using it.
  186.     Cluster Comments: For purposes of building user interface to select
  187. clusters, each link to a cluster can specify a "comment", up to 34
  188. characters long, which describes what this cluster actually is. However,
  189. since there can only be one comment for a cluster, the comment from the
  190. first link is the one used.
  191.  
  192.     One of the advantages of the cluster model is that applications can be
  193. started up in any order and still work. The following are suggestions as
  194. to how applications should handle linkages:
  195.  
  196.     1. An application should allow the user to see a list of existing
  197. clusters (which CAMD can provide), or allow the user to type in a new
  198. cluster name. [Issue: Should the word "cluster" be used in UI?]
  199.     2. The application should save the current linkages either in the
  200. applications "settings", or embedded in the document or performance file
  201. (perhaps using an IFF chunk). When the application is restarted (or that
  202. performance loaded or whatever) the application should then automatically
  203. establish the links specified.
  204.  
  205.     If every application does this, then it will be easy for the user to set
  206. up the same configuration of linkages as they did last time, even if they
  207. launch their applications in a different order. Even if the applications
  208. are invoked via a script, the network of applications can come into
  209. existence automatically.
  210.     (Eventually we will want to have a "performance manager" which can
  211. "snapshot" a whole network of apps, allowing the user to go back to that
  212. "state" later. This might be done using ARexx).
  213.  
  214. MIDI Timestamps
  215. ~~~~~~~~~~~~~~~
  216.     Each incoming MIDI message may be timestamped, however, you must
  217. supply a source of timing information (the recommended method is to use
  218. RealTime.library, however many other timestamp sources are possible).
  219.     You can tell CAMD to use a particular timig source. The MidiNode
  220. contains a pointer (of type LONG *), which may be pointed to the source of
  221. timestamps. Whenever a MidiMsg is received, the longword that is pointed
  222. to by this pointer is used as the current time, and copied into the
  223. MidiMsg. Normally, what you would want to do is point this pointer at a
  224. longword that was contually being updated. Note that in this fashion, your
  225. application can have timestamps in any format it wants, since CAMD never
  226. looks at the timestamp field once it is set.
  227.     One important point is that the timestamp is set at the time the
  228. message is placed into the receiver's buffer. It would have been nice to
  229. timestamp the messages at the interrupt time of the first MIDI status
  230. byte, however this would have made the cluster model of distribution
  231. impossible. Application which desire ultimate accuracy should probably
  232. adjust the timestamp to compensate for the length of the MidiMsg.
  233.  
  234. Interfacing to Hardware
  235. ~~~~~~~~~~~~~~~~~~~~~~~
  236.     CAMD maintains a list of hardware drivers which are used to access
  237. serial ports, DSP boards, or any other hardware interface. A preferences
  238. file (ENV:sys/midi.prefs) is used to indicate which hardware drivers
  239. should be loaded and which ports should be activated. Note that using file
  240. notification, CAMD is capable of changing this setup at any time, even
  241. while applications are running.
  242.     Hardware drivers live in the directory DEVS:midi. They can be created
  243. by third-party developers, and are fairly simple.
  244.     CAMD maintains a task for each input MIDI stream. This task is
  245. responsible for reading bytes from the hardware, parsing them into
  246. MidiMsgs, and sending them to a cluster. The cluster name is specified in
  247. the preferences file, on a per-port basis.
  248.  
  249. Credits
  250. ~~~~~~~
  251.     CAMD has a long and convoluted history. It was originally created at
  252. Carnegie-Mellon university by Roger B. Dannenberg and Jean-Christophe
  253. Dhellemmes. After that is was worked on by Bill Barton, and later by
  254. Darius Taghavy, followed by Carolyn Scheppner. The final form of the
  255. design was conceived by David Joiner (a.k.a. Talin) and implemented by Joe
  256. Pearce.
  257.